═══ 1. HTML-Ed REXX Functions ═══

The following functions are available for use in your REXX Macros: 

      hmChangeFilename 
      hmCharFromLine 
      hmCharsToTags 
      hmClear 
      hmCloseFile 
      hmConvertSlashes 
      hmCopy 
      hmCurrentFile 
      hmCut 
      hmDelete 
      hmDeselectAll 
      hmDisableRefresh 
      hmEnableRefresh 
      hmExit 
      hmFind 
      hmGoToLine 
      hmInsert 
      hmInsertFile 
      hmLineFromChar 
      hmNew 
      hmOpen 
      hmOpenOutputWindow 
      hmPaste 
      hmQueryChanged 
      hmQueryFilename 
      hmQueryLineCount 
      hmQueryLineLength 
      hmQuerySel 
      hmQuerySelText 
      hmQueryTextLength 
      hmQueryWrap 
      hmRemoveTags 
      hmResetUndo 
      hmRingLeft 
      hmRingFiles 
      hmRingRight 
      hmSaveAll 
      hmSaveAs 
      hmSaveASCII 
      hmSaveCurrent 
      hmSaveOptions 
      hmSay 
      hmSelectAll 
      hmSetChanged 
      hmSetSel 
      hmSetWrap 
      hmStatusSay 
      hmSwitchTo 
      hmTagsCase 
      hmUndo 
      hmVersion 
      hmWrapAround 


═══ <hidden> Introduction ═══

Welcome to the HTML-Ed Programmer's Reference! 

HTML-Ed extends the REXX language with 52 new functions.  These functions are 
explained in this reference manual. 

If this is the first time you have used the .HM Macro functions, please read 
over this entire document before proceeding.  Many of the functions have 
important remarks that you should be aware of before using them. 

Things to remember: 

     Name your HTML-Ed macros with an .HM extension.  This is not strictly 
      necessary, but it will help you to tell apart normal REXX .CMD files and 
      REXX macros that use the HTML-Ed extended functions. 

     The .HM macro functions are very powerful - but power comes at a price. 
      The functions are not crash proof and you can crash HTML-Ed if you are 
      not careful.  Always check the return codes a function returns (unless 
      there is only one possible return code) and take appropriate action.  For 
      functions that require parameters, make sure you are passing it a correct 
      value. 

     Take special care that you do not enter an infinite loop.  HTML-Ed will 
      not be able to recover from a stuck macro. 

     Your macro runs on HTML-Ed's main thread!  (This will change in the 
      future).  Therefore, while your macro is running you will not be able to 
      interact with any windows (the message queue will be "hung").  If your 
      macro is taking a long time to complete, or if it gets stuck in an 
      infinite loop, pressing Ctrl+ESC a few times should bring up a dialog 
      that will allow you to kill HTML-Ed (alternatively, you could use a 
      process killer such as Watchcat to kill HTML-Ed).  It is a good idea to 
      make sure your macros are short. 

     An insertion point is just a number.  "0" is the insertion point before 
      the first character in the editor.  Take special care to ensure that any 
      insertion points you are using are valid - any time you insert or remove 
      any text the insertion points after the changed portion will be invalid. 
      Take extreme care when writing looping search/replace macros as it is 
      very easy to become stuck in an infinite loop. 

     Use hmSay instead of Say.  If more than 32kb of text is written to stdout 
      HTML-Ed will appear to crash (in reality, HTML-Ed is waiting for the 
      macro to finish and the macro is waiting for the unnamed pipe to be 
      cleared - so nothing happens).  This will be addressed in a future 
      version. 

 If you have problems: 

      Nothing appears to be happening! 

                         .HM macros simply stop execution when there is an 
                          error.  When an error occurs, anything written to 
                          stdout does not get copied to the output window (use 
                          hmSay to overcome this problem).  If you have a 
                          syntax error in your program and you have been using 
                          say instead of hmSay it may appear as if nothing has 
                          happened. 

                         You can use hmSay to help track down the problem. 

      One of the functions doesn't work as it should! 

                         First, make sure you read (and re-read) all the 
                          appropriate information in this manual.  If the 
                          problem persists, contact me. 

 Contacting the author: 

     HTML-Ed's author, Ian Prest, may be contacted in the following ways: 

      email:         ianprest@connect.reach.net (put "HTML-Ed" somewhere on the 
                     subject line) 

      snail mail: 

                                          Ian Prest
                                          R.R.#1
                                          Shannonville, Ontario
                                          K0K 3A0
                                          re: HTML-Ed

     Visit the HTML-Ed Home Page on the internet! 
      http://www.wp.com/ianprest/htmled.html 


═══ 1.1. hmChangeFilename ═══

 Function:  hmChangeFilename 

 Purpose:   to change the filename of the current editor 

 Syntax:    rc = hmChangeFilename(file) 

           file           the new filename 

 Returns:  0 

 Remarks: 

           hmChangeFilename changes the name of the current file, but does not 
           save anything with the new filename, and does not alter the file's 
           "changed" flag. 

           hmChangeFilename is usually used after a call to hmSaveAs. 

 Example: 


                      /* Save the file with a new filename */
                      call hmSaveAs "newfile.htm"

                      /* Update the titlebar's filename to reflect the change */
                      call hmChangeFilename "newfile.htm"


═══ 1.2. hmCharFromLine ═══

 Function:  hmCharFromLine 

 Purpose:   to find the insertion point of the first character of a line 

 Syntax:    ipt = hmCharFromLine(line) 

           line           line number of interest 

 Returns:  insertion point of the first character of line 'line' 

 Remarks: 

           Use hmCharFromLine to determine where a line starts. 

 Example: 


                      /* example to "home" the cursor */

                      /* get cursor position */
                      ipt = hmQuerySel("cursor")

                      /* get current line */
                      line = hmLineFromChar(ipt)

                      /* find start of current line */
                      ipt = hmCharFromLine(line)

                      /* set cursor position */
                      call hmSetSel ipt,ipt


═══ 1.3. hmCharsToTags ═══

 Function:  hmCharsToTags 

 Purpose:   to convert characters to HTML character identities 

 Syntax:    rc = hmCharsToTags() 

 Returns: 

           0              No error 
           1              No text was selected 

 Remarks: 

           hmCharsToTags works exactly as the "Convert characters to tags" menu 
           function does, converting all the characters in the selected text to 
           their HTML equivilants. 

 Example: 


                      /* Convert all special characters to tags */
                      call hmCharsToTags


═══ 1.4. hmClear ═══

 Function:  hmClear 

 Purpose:   to delete the current selection 

 Syntax:    rc = hmClear() 

 Returns:  0 

 Remarks: 

 Example: 


                      /* delete the current selection */
                      call hmClear


═══ 1.5. hmCloseFile ═══

 Function:  hmCloseFile 

 Purpose:   to close the current file 

 Syntax:    rc = hmCloseFile() 

 Returns: 

           0              No error 
           1              Last file closed - HTML-Ed will now exit 

 Remarks: 

           The user is not prompted to save the current file (if it has not 
           been saved) before it is closed.  It is up to the macro to ensure 
           the file is saved if necessary. 

           If this function returns "1" then your macro should exit as soon as 
           possible becuase HTML-Ed is trying to exit.  Any furthur actions 
           performed on any (non-existant) files will probably crash HTML-Ed. 

 Example: 


                      /* Close the current file */
                      rc = hmCloseFile()

                      /* Exit macro if necessary */
                      if rc=1 then exit


═══ 1.6. hmConvertSlashes ═══

 Function:  hmConvertSlashes 

 Purpose:   to convert backslashes to forward slashes 

 Syntax:    rc = hmConvertSlashes() 

 Returns: 

           0              No error 
           1              No text was selected 

 Remarks: 

           hmConvertSlashes works exactly as the "Convert \ to /" menu function 
           does, converting all the backslashes in the selected text. 

 Example: 


                      /* Convert all backslashes to forward slashes */
                      call hmConvertSlashes


═══ 1.7. hmCopy ═══

 Function:  hmCopy 

 Purpose:   to copy the current selection to the clipboard 

 Syntax:    rc = hmCopy() 

 Returns:  0 

 Remarks: 

 Example: 


                      /* copy the current selection to the clipboard */
                      call hmCopy


═══ 1.8. hmCurrentFile ═══

 Function:  hmCurrentFile 

 Purpose:   to return the name of the current file 

 Syntax:    title = hmCurrentFile() 

 Returns:   window title of the current file 

 Remarks: 

           The title returned can be used to switch back to this file later. 

           If you desire the actual filename of the current file, follow this 
           call with a call to hmQueryFilename. 

 Example: 


                      /* Get current window title */
                      file = hmCurrentFile()

                      /* Display it */
                      call hmSay file


═══ 1.9. hmCut ═══

 Function:  hmCut 

 Purpose:   to cut the current selection to the clipboard 

 Syntax:    rc = hmCut() 

 Returns:  0 

 Remarks: 

 Example: 


                      /* cut the current selection */
                      call hmCut


═══ 1.10. hmDelete ═══

 Function:  hmDelete 

 Purpose:   to delete text from a specified location 

 Syntax:    rc = hmDeselectAll(start,length) 

           start          insertion point to start deleting at 

           length         number of characters to delete 

 Returns:  number of characters deleted 

 Remarks: 

 Example: 


                      /* Delete the first 15 characters */
                      call hmDelete 0, 15


═══ 1.11. hmDeselectAll ═══

 Function:  hmDeselectAll 

 Purpose:   to deselect all the text in the current file 

 Syntax:    rc = hmDeselectAll() 

 Returns:  0 

 Remarks: 

           hmDeselectAll works exactly as the "Deselect All" menu function 
           does. 

 Example: 


                      /* Deselect All Text */
                      call hmDeselectAll


═══ 1.12. hmDisableRefresh ═══

 Function:  hmDisableRefresh 

 Purpose:   to disable the editor when about to perform heavy editing 
           operations 

 Syntax:    rc = hmDisableRefresh() 

 Returns:  0 

 Remarks: 

           Calls to hmDisableRefresh must have a corresponding call to 
           hmEnableRefresh before your macro ends. 

           If you omit the hmEnableRefresh, you will not be able to use the 
           file that was disabled - the mouse will turn into a clock cursor 
           when over the editor, and the editor will not accept any keyboard 
           input.  However, other files in the ring (if they weren't disabled) 
           will not be affected and HTML-Ed will continue running so you can 
           still save the file and exit. 

 Example: 


                      /* Disable the editor */
                      call hmDisableRefresh

                      /* do some editing */
                        ...

                      /* Enable it again */
                      call hmEnableRefresh


═══ 1.13. hmEnableRefresh ═══

 Function:  hmEnableRefresh 

 Purpose:   to enable the editor after a call to hmDisableRefresh 

 Syntax:    rc = hmEnableRefresh() 

 Returns:  0 

 Remarks: 

           Calls to hmDisableRefresh must have a corresponding call to 
           hmEnableRefresh before your macro ends.  See hmDisableRefresh for 
           furthur information. 

 Example: 


                      /* Disable the editor */
                      call hmDisableRefresh

                      /* do some editing */
                        ...

                      /* Enable it again */
                      call hmEnableRefresh


═══ 1.14. hmExit ═══

 Function:  hmExit 

 Purpose:   to exit HTML-Ed 

 Syntax:    rc = hmExit() 

 Returns:  0 

 Remarks: 

           The user is not prompted to save any of the files in the ring before 
           they are closed.  It is up to the macro to ensure the files are 
           saved. 

           If you use this function in your macro it should be the last 
           instruction before the macro ends. 

 Example: 


                      /* Exit HTML-Ed */
                      call hmExit
                      exit


═══ 1.15. hmFind ═══

 Function:  hmFind 

 Purpose:   to find a text string in the current file 

 Syntax:    ipt = hmFind(text,[start],[stop],[cs]) 

           text           text string to search for 

           start          insertion point from which to start searching 

           stop           insertion point to stop searching at 

           cs=0           case insensitive (default) 
           cs=1           case sensitive 

 Returns: 

           -1             Text not found 
           other          Insertion point of the end of the text that was found 

 Remarks: 

           Specifying a start position of -1 starts the search from the cursor 
           (the default if 'start' is omitted).  A stop position of -1 stops 
           the search at the end of the text (the default if 'stop' is 
           omitted). 

           If the text string is found the text string is selected.  The 
           insertion point (ipt) of the cursor is then returned.  You can 
           replace the text by simply calling hmInsert. 

           To search for the next ocurrance of the string, simply search again, 
           starting from the cursor (if the cursor position hasn't changed) or 
           from ipt (the return value from the last call to hmFind). 

           If you have replaced the text, search from "ipt - length(text) + 
           length(replace_string)." 

 Example: 


                      /* Search for a string */
                      text = "Find Me!"

                      ipt = hmSearch(text,,,1)   /* Case sensitive!              */
                      ipt = hmSearch(text)       /* Case insensitive!            */

                      ipt = hmSearch(text,0)     /* Start from beginning of file */
                      ipt = hmSearch(text,ipt)   /* Search again                 */


═══ 1.16. hmGoToLine ═══

 Function:  hmGoToLine 

 Purpose:   to move the cursor to a specified line 

 Syntax:    rc = hmGoToLine(line) 

           line           line number to move the cursor to 

 Returns:   0 

 Remarks: 

           hmGoToLine moves the cursor to the start of the specified line. If 
           the line specified is greater than the last line in the file, the 
           cursor will be moved to the start of the last line.  If zero is 
           specified for the line, the cursor will be moved to the start of the 
           current line. 

 Example: 


                      /* Move to line 6 */
                      call hmGoToLine 6


═══ 1.17. hmInsert ═══

 Function:  hmInsert 

 Purpose:   to insert some text at the cursor 

 Syntax:    rc = hmInsert(text) 

           text           text string to insert at the cursor 

 Returns:   0 

 Remarks: 

           Any selected text at the time of the call to hmInsert will be 
           replaced with the text string being inserted. 

 Example: 


                      /* insert a text string */
                      call hmInsert "This is some inserted text."

                      /* insert a text string with a newline character */
                      call hmInsert "This is an inserted line!"d2c(10)


═══ 1.18. hmInsertFile ═══

 Function:  hmInsertFile 

 Purpose:   to insert a text file into the current file at the cursor 

 Syntax:    rc = hmInsertFile(filename) 

           filename       the file to insert into the current file 

 Returns: 

           0              No Error 
           1              Error opening file 

 Remarks: 

           hmInsertFile (like the other file manipulation functions) will not 
           inform the user with a message box when there is a file error.  You 
           must check the return code to ensure the file was inserted 
           correctly. 

 Example: 


                      /* Insert a text file at the cursor */
                      rc = hmInsertFile("insert.txt")

                      /* Inform user on error */
                      if rc<>0 then call hmStatusSay "Error loading file!",30
                      else call hmStatusSay "Done.",30


═══ 1.19. hmLineFromChar ═══

 Function:  hmLineFromChar 

 Purpose:   to query the line number of a specified insertion point 

 Syntax:    line = hmLineFromChar(ipt) 

           ipt            the insertion point of interest 

 Returns:  line number 

 Remarks: 

 Example: 


                      /* find out what line the cursor is on */
                      ipt = hmQuerySel("cursor")
                      line = hmLineFromChar(ipt)

                      /* tell user */
                      call hmStatusSay "We're on line #"line"!",30


═══ 1.20. hmNew ═══

 Function:  hmNew 

 Purpose:   to open a new, untitled document, and switch to it 

 Syntax:    rc = hmNew() 

 Returns:   0 

 Remarks: 

           hmNew would be most useful for a macro that generates a complete 
           HTML file from scratch.  hmNew switches to the new document after 
           creating it. 

 Example: 


                      /* Open a new document and create a (very simple) HTML skeleton */
                      call hmNew
                      call hmInsert "<HTML><HEAD></HEAD><BODY></BODY></HTML>"


═══ 1.21. hmOpen ═══

 Function:  hmOpen 

 Purpose:   to open send one-line status updates to the user via the status 
           line 

 Syntax:    rc = hmOpen(filename) 

           filename       name of the file to open 

 Returns: 

           0              No Error 
           1              Error opening file. 

 Remarks: 

           hmOpen (like the other file manipulation functions) will not inform 
           the user with a message box when there is a file error.  You must 
           check the return code to ensure the file was opened correctly. 

           After the file is opened, it will become the current file in the 
           ring. 

 Example: 


                      /* Open a file */
                      rc = hmOpen("myfile.htm")

                      /* Modify it */
                      if rc = 0 then ...

                      /* Save the file */
                      call hmSaveCurrent


═══ 1.22. hmOpenOutputWindow ═══

 Function:  hmOpenOutputWindow 

 Purpose:   to open the Output Window 

 Syntax:    rc = hmOpenOutputWindow() 

 Returns:   0 

 Remarks: 

           hmOpenOutputWindow should be used before you display any important 
           data to the Output Window.  If hmOpenOutputWindow isn't called, the 
           user may never see what you write unless they open the Output Window 
           manually, or have turned on the "Open Output Window when starting 
           external process" option. 

 Example: 


                      /* Open the Output Window and write some text to it */
                      call hmOpenOutputWindow
                      call hmSay "Hello World!"


═══ 1.23. hmPaste ═══

 Function:  hmPaste 

 Purpose:   to paste the contents of the clipboard to the editor 

 Syntax:    rc = hmPaste() 

 Returns:  0 

 Remarks: 

 Example: 


                      /* paste clipboard contents at cursor */
                      call hmPaste


═══ 1.24. hmQueryChanged ═══

 Function:  hmQueryChanged 

 Purpose:   to query the "changed" flag for the current file 

 Syntax:    rc = hmQueryChanged() 

 Returns: 

           0              file is unchanged since the last save 
           1              file has been changed 

 Remarks: 

           You must check the changed flag before you close files (or exit 
           HTML-Ed) if you want to make sure the file has been saved. 

 Example: 


                      /* query changed status */
                      wrap = hmQueryChanged()
                      if wrap=1 then call hmSay "File has been modified!"
                      else call hmSay "File is unchanged."


═══ 1.25. hmQueryFilename ═══

 Function:  hmQueryFilename 

 Purpose:   to query the filename of a certain window title 

 Syntax:    file = hmQueryFilename(title) 

           title          window title of the desired file 

 Returns:  filename of the desired file 

 Remarks: 

           You must call hmQueryFilename to get the actual filename after a 
           call to hmCurrentFile or hmRingFiles. 

           If a file is untitled, or if the file does not exist in the ring, an 
           empty string ("") is returned. 

 Example: 


                      /* display actual filename of current file */
                      title = hmCurrentFile()
                      filen = hmQueryFilename(title)
                      call hmSay filen


═══ 1.26. hmQueryLineCount ═══

 Function:  hmQueryLineCount 

 Purpose:   to query the line count for the current file 

 Syntax:    lines = hmQueryLineCount() 

 Returns:  number of lines in the current file 

 Remarks: 

 Example: 


                      /* how many lines? */
                      lines = hmQueryLineCount()
                      call hmSay "There are "lines" lines in this file."


═══ 1.27. hmQueryLineLength ═══

 Function:  hmQueryLineLength 

 Purpose:   to query the length from a specified insertion point to the end of 
           the line 

 Syntax:    lines = hmQueryLineLength(ipt) 

           ipt            insertion point to start from 

 Returns:  length from ipt to the end of the line 

 Remarks: 

 Example: 


                      /* delete to end of line */
                      cur = hmQuerySel("cursor")
                      len = hmQueryLineLength(cur)
                      call hmDelete cur,len-1


═══ 1.28. hmQuerySel ═══

 Function:  hmQuerySel 

 Purpose:   to query the cursor or anchor points 

 Syntax:    ipt = hmQuerySel(type) 

           type = 

                          "anchor"       request the anchor point 
                          "cursor"       request the cursor position 
                          "min"          request the minimum selection point 
                                         (whether it is the cursor or anchor 
                                         point) 
                          "max"          request the maximum selection point 
                                         (whether it is the cursor or anchor 
                                         point) 

 Returns:  the requested insertion point 

 Remarks: 

           The cursor and anchor points are the endpoints of the current 
           selection.  The cursor point is the endpoint that the cursor is at, 
           and the anchor point is the other endpoint. 

           If there is no selected text, the cursor and anchor points (and, 
           therefore, the min and max points) will be the same. 

 Example: 


                      /* delete to end of line */
                      cur = hmQuerySel("cursor")
                      len = hmQueryLineLength(cur)
                      call hmDelete cur,len-1


═══ 1.29. hmQuerySelText ═══

 Function:  hmQuerySelText 

 Purpose:   to query the selected text 

 Syntax:    text = hmQuerySelText() 

 Returns:  the selected text 

 Remarks: 

           If there is no selected text, hmQuerySelText returns an empty string 
           (""). 

 Example: 


                      /* get 15 characters, starting at the cursor */
                      cur = hmQuerySel("cursor")
                      call hmSelSet cur+15,cur
                      text = hmQuerySelText()
                      call hmSelSet cur,cur

                      /* print it out */
                      call hmSay text


═══ 1.30. hmQueryTextLength ═══

 Function:  hmQueryTextLength 

 Purpose:   to query the length of the current document 

 Syntax:    len = hmQueryTextLength() 

 Returns:  length of the current document 

 Remarks: 

           A good use for hmQueryTextLength is to find the insertion point of 
           the end of the document. 

 Example: 


                      /* get length of file */
                      len = hmQueryTextLength()


═══ 1.31. hmQueryWrap ═══

 Function:  hmQueryWrap 

 Purpose:   to query the word wrap status of the current file 

 Syntax:    rc = hmQueryWrap() 

 Returns: 

           0              Word wrap off 
           1              Word wrap on 

 Remarks: 

           The word wrap status applies only to the current file.  Another file 
           may have a different word wrap status. 

 Example: 


                      /* query wrap status */
                      wrap = hmQueryWrap()
                      if wrap=1 then call hmSay "Word wrap enabled!"
                      else call hmSay "Word wrap disabled."


═══ 1.32. hmRemoveTags ═══

 Function:  hmRemoveTags 

 Purpose:   to remove the HTML tags from the selected text 

 Syntax:    rc = hmRemoveTags() 

 Returns: 

           0              No error 
           1              No text was selected 

 Remarks: 

           hmRemoveTags works exactly as the "Remove Tags" menu function does, 
           removing all the tags from the selected text. 

 Example: 


                      /* Remove tags in the selected text */
                      call hmRemoveTags


═══ 1.33. hmResetUndo ═══

 Function:  hmResetUndo 

 Purpose:   to prevent the user from undoing something 

 Syntax:    rc = hmResetUndo() 

 Returns:   0 

 Remarks: 

           If you call hmResetUndo after you change the document, the user will 
           be prevented from undoing your change. 

 Example: 


                      /* Prevent an Undo */
                      call hmResetUndo


═══ 1.34. hmRingLeft ═══

 Function:  hmRingLeft 

 Purpose:   to move left in the file ring 

 Syntax:    rc = hmRingLeft() 

 Returns:   0 

 Remarks: 

 Example: 


                      /* Move left in the file ring */
                      call hmRingLeft


═══ 1.35. hmRingFiles ═══

 Function:  hmRingFiles 

 Purpose:   to return a list of all the files in the file ring 

 Syntax:    rc = hmRingFiles(stem[,options]) 

           stem           The name of the stem variable to return the titles 
                          in. 

           options        If the options string contains an 'F', hmRingFiles 
                          will only return those files that have been saved 
                          (not untitled), and only one instance of each file. 

 Returns:   0 

 Remarks: 

           The number of files will be returned in stem.0 and the actual 
           filenames are returned in stem.n where n is a number from 1 to 
           stem.0, much the same as SysFileTree returns a list of files. 

           Currently the "F" (Files only) option is the only available option. 

           Note that the values returned are not filenames - they are window 
           titles.  To find the filename of a certain window title, follow this 
           call with a call to hmQueryFilename. 

 Example: 


                      /* Get the file ring in the 'ring' stem variable */
                      call hmRingFiles "ring"

                      /* Display the file ring */
                      call hmOpenOutputWindow
                      do i=1 to ring.0
                         call hmSay ring.i
                      end


═══ 1.36. hmRingRight ═══

 Function:  hmRingRight 

 Purpose:   to move right in the file ring 

 Syntax:    rc = hmRingRight() 

 Returns:   0 

 Remarks: 

 Example: 


                      /* Move right in the file ring */
                      call hmRingRight


═══ 1.37. hmSaveAll ═══

 Function:  hmSaveAll 

 Purpose:   to save all named (not untitled) files in the ring 

 Syntax:    rc = hmSaveAll() 

 Returns: 

           0              No Error 
           1              Error opening file 
           2              Error writing to file 

 Remarks: 

           On error, hmSaveAll makes the file that caused the error the current 
           file in the ring. 

           Unlike hmSaveCurrent, unnamed files and files that haven't been 
           changed do not cause errors.  These files are not saved, however. 

           The "changed" flag is cleared for all saved files. 

 Example: 


                      /* Save all the files in the ring */
                      rc = hmSaveAll()

                      /* if there was an error, inform user */
                      if rc<>0 then call hmStatusSay "Error saving this file!",30
                      else call hmStatusSay "Done!",30


═══ 1.38. hmSaveAs ═══

 Function:  hmSaveAs 

 Purpose:   to save the current file with a given filename 

 Syntax:    rc = hmSaveAs(filename) 

           filename       the filename with which to save the current file 

 Returns: 

           0              No Error 
           1              Error opening file 
           2              Error writing to file 

 Remarks: 

           hmSaveAs (like the other file manipulation functions) will not 
           inform the user with a message box when there is a file error.  You 
           must check the return code to ensure the file was saved correctly. 

           hmSaveAs will also not warn you about an existing file - it will 
           overwrite the file automatically.  If you don't wish to overwrite an 
           existing file you must use standard REXX functions to determine if 
           the file already exists. 

           If an existing file is overwritten, the existing EA's are preserved. 
           It is up to the macro to remove the EA's if desired. 

           Note that unlike the "Save As..." menu option, the in-memory 
           filename (the one on the titlebar) for the current file is not 
           changed. You can use the hmChangeFilename function for that purpose. 

 Example: 


                      /* Modify the current file */
                      call hmInsert ...

                      /* Save it under a new filename */
                      call hmSaveAs "newfile.htm"

                      /* Undo the last change */
                      call hmUndo


═══ 1.39. hmSaveASCII ═══

 Function:  hmSaveASCII 

 Purpose:   to save an ASCII version of the current file with a given filename 

 Syntax:    rc = hmSaveASCII(filename) 

           filename       the filename with which to save the current file as 
                          ASCII 

 Returns: 

           0              No Error 
           1              Error opening file 
           2              Error writing to file 

 Remarks: 

           hmSaveASCII (like the other file manipulation functions) will not 
           inform the user with a message box when there is a file error.  You 
           must check the return code to ensure the file was saved correctly. 

           hmSaveASCII will also not warn you about an existing file - it will 
           overwrite the file automatically.  If you don't wish to overwrite an 
           existing file you must use standard REXX functions to determine if 
           the file already exists. 

           If an existing file is overwritten, the existing EA's are preserved. 
           It is up to the macro to remove the EA's if desired. 

 Example: 


                      /* Save an ascii version of the current file */
                      rc = hmSaveASCII("myfile.txt")

                      /* Inform user on error */
                      if rc<>0 then call hmStatusSay "Error saving as ASCII!",30
                      else call hmStatusSay "Saved!",30


═══ 1.40. hmSaveCurrent ═══

 Function:  hmSaveCurrent 

 Purpose:   to save the current file in the file ring 

 Syntax:    rc = hmSaveCurrent() 

 Returns: 

           0              No Error 
           1              Error opening file 
           2              Error writing to file 
           3              File was unchanged (save was unnecessary) 
           4              No filename (current file is untitled) 

 Remarks: 

           hmSaveCurrent (like the other file manipulation functions) will not 
           inform the user with a message box when there is a file error.  You 
           must check the return code to ensure the file was saved correctly. 

           The "changed" flag is cleared if the file is saved correctly. 

 Example: 


                      /* Open a file */
                      rc = hmOpen("myfile.htm")

                      /* Modify it */
                      if rc = 0 then ...

                      /* Save the file */
                      call hmSaveCurrent


═══ 1.41. hmSaveOptions ═══

 Function:  hmSaveOptions 

 Purpose:   to save the current options 

 Syntax:    rc = hmSaveOptions() 

 Returns:  0 

 Remarks: 

           hmSaveOptions works just like the "Save Options/Position" menu 
           function.  It causes all the options and window positions to be 
           saved. 

 Example: 


                      /* Save options */
                      call hmSaveOptions


═══ 1.42. hmSay ═══

 Function:  hmSay 

 Purpose:   to send textual information to the user via the Output Window 

 Syntax:    rc = hmSay(text) 

           text           a text string to be displayed in the Output Window 

 Returns:   0 

 Remarks: 

           If a .CMD or .HM REXX Macro sends more than 32kb of data to stdout, 
           HTML-Ed will crash (this limit does not exist for EXE's!).  This 
           limit should be more than enough for all your needs.  However, if 
           you need to display a significant amount of data, you should use 
           hmSay instead of say because hmSay does not suffer from this 
           limitation. 

           Note that if you mix calls to say and hmSay, you will not get the 
           results you expected.  The output from all calls to hmSay will be 
           displayed before the output from all calls to say.  Therefore, you 
           should avoid mixing calls to say and hmSay. 

 Example: 


                      /* Display text in Output Window */
                      call hmSay "Hello World!"


═══ 1.43. hmSelectAll ═══

 Function:  hmSelectAll 

 Purpose:   to select all the text in the current file 

 Syntax:    rc = hmSelectAll() 

 Returns:  0 

 Remarks: 

           hmSelectAll works exactly as the "Select All" menu function does. 

 Example: 


                      /* Select All Text */
                      call hmSelectAll


═══ 1.44. hmSetChanged ═══

 Function:  hmSetChanged 

 Purpose:   to set a document's "changed" flag 

 Syntax:    rc = hmSetChanged(changed) 

           changed=0      unchanged 
           changed=1      changed 

 Returns:   0 

 Remarks: 

 Example: 


                      /* turn off changed flag */
                      call hmSetChanged 0


═══ 1.45. hmSetSel ═══

 Function:  hmSetSel 

 Purpose:   to set the anchor and cursor points 

 Syntax:    rc = hmSetWrap(anchor, cursor) 

           anchor         insertion point of the anchor point 

           cursor         insertion point of the cursor 

 Returns:   0 

 Remarks: 

           If you simply wish to move the cursor, call hmSetSel with the same 
           value for the cursor and anchor. 

 Example: 


                      /* move the cursor to the beginning of the file */
                      call hmSetSel 0, 0


═══ 1.46. hmSetWrap ═══

 Function:  hmSetWrap 

 Purpose:   to set the word wrap status of the current file 

 Syntax:    rc = hmSetWrap(wrap) 

           wrap=0         word wrap off 
           wrap=1         word wrap on 

 Returns:   0 

 Remarks: 

           Note that the word wrap status will be changed for the current file 
           only - not all the files in the ring.  However, if you open or 
           create another file then the new file will inherit the word wrap 
           style from the current file at the time of its creation. 

 Example: 


                      /* turn on word wrap */
                      call hmSetWrap 1


═══ 1.47. hmStatusSay ═══

 Function:  hmStatusSay 

 Purpose:   to send one-line status updates to the user via the status line 

 Syntax:    rc = hmStatusSay(text[,time]) 

           text           a text string to be displayed on the status line 

           time           approximate time (in tenths of a second) that the 
                          text should be displayed before being cleared.  If 
                          zero, or if omitted, the text will be displayed until 
                          the next call to hmStatusSay, or until HTML-Ed writes 
                          to the status line itself (such as during Open and 
                          Save operations). 

 Returns:   0 

 Remarks: 

           hmStatusSay is very useful since it allows you to quickly inform the 
           user of your macro's status without requiring that the Output Window 
           be displayed. 

 Example: 


                      /* Display text on the status line for three seconds */
                      call hmStatusSay "Hello World!", 30

                      /* Display text on the status line indefinitely*/
                      call hmStatusSay "Hello Again!"


═══ 1.48. hmSwitchTo ═══

 Function:  hmSwitchTo 

 Purpose:   to switch to a specified file in the file ring 

 Syntax:    rc = hmSwitchTo(file) 

           file           The filename of the file to switch to 

 Returns: 

           0              No Error 
           1              Couldn't find file in ring 

 Remarks: 

           You should note that when switching to a file you must specify the 
           complete filename and path.  You may also switch to an untitled file 
           or a second instance of a file by specifying exactly what appears in 
           the title bar.  See the examples. 

           Note also that this is not case sensitive.  "E:\HOME.HTM" is treated 
           exactly the same as "e:\home.htm". 

 Example: 


                      /* Switch to a file */
                      call hmSwitchTo "F:\homepage\home.htm"

                      /* Switch to another instance of the same file */
                      call hmSwitchTo "F:\homepage\home.htm:1"

                      /* Switch to untitled file #2 */
                      call hmSwitchTo "Untitled #2"


═══ 1.49. hmTagsCase ═══

 Function:  hmTagsCase 

 Purpose:   to convert the case of HTML tags 

 Syntax:    rc = hmTagsCase([case]) 

           case = 0       lowercase 
           case = 1       uppercase (the default if parameter is omitted) 

 Returns: 

           0              No error 
           1              No text was selected 

 Remarks: 

           hmTagsCase works exactly as the "Convert tags" menu functions do, 
           converting the case of all the HTML tags in the selected text. 

 Example: 


                      /* Convert tags to uppercase */
                      call hmTagsCase

                      /* Convert tags to lowercase */
                      call hmTagsCase 0


═══ 1.50. hmUndo ═══

 Function:  hmUndo 

 Purpose:   to undo/redo the last operation 

 Syntax:    rc = hmUndo() 

 Returns: 

           0              No error 
           1              Undo was not performed (usually becuase there was 
                          nothing to undo) 

 Remarks: 

           Calling hmUndo twice in a row will redo the undone operation. 

 Example: 


                      /* undo something */
                      call hmUndo


═══ 1.51. hmVersion ═══

 Function:  hmVersion 

 Purpose:   to return the name and version number of the host program 

 Syntax:    version = hmVersion() 

 Returns:   version string (eg. "HTML-Ed v0.96b") 

 Remarks: 

           You should check the version of HTML-Ed that is being used before 
           you use functions introduced in future versions.  I will strive to 
           make the HM macro functions fully backward-compatible. 

           However, unless your macro is specific to HTML-Ed, do not enforce 
           the presence of the "HTML-Ed" text at the beginning of the string - 
           only check the version number.  I intend to use the HM macro 
           functions in a future project and most, if not all of the HM macro 
           functions will be the same (most likely only a few functions will be 
           missing - mainly ones specific to HTML like hmSaveASCII, 
           hmConvertSlashes, etc). 

 Example: 


                      /* Get version string */
                      version = hmVersion()

                      /* Display version */
                      call hmSay version


═══ 1.52. hmWrapAround ═══

 Function:  hmWrapAround 

 Purpose:   to wrap two text strings around the selected text 

 Syntax:    rc = hmWrapAround(open,close) 

           open           text string to insert before the selection 

           close          text string to insert after the selection 

 Returns:  0 

 Remarks: 

           This function is the same one used by many of HTML-Ed's tag 
           functions. 

 Example: 


                      /* simulate a "Styles/Bold" menu choice */
                      call hmWrapAround "<B>","</B>"


═══ 2. Examples ═══

The following examples are also available on disk: 

      AUTODATE.HM 


═══ <hidden> Examples Introduction ═══

These are some example .HM macros.  Visit the HTML-Ed Hope Page at 
http://www.wp.com/ianprest/htmled.html for new example macros submitted by 
users (please mail me any macros you write that you think others would find 
useful). 


═══ 2.1. AUTODATE.HM ═══

This macro replaces the text between the comment tags <!-- AUTODATE --> and 
<!-- /AUTODATE --> and replaces the text between them with the current date. 


/* .HM Macro to replace a date in the current file with a new date */

starttext = "<!-- AUTODATE -->"
stoptext = "<!-- /AUTODATE -->"

/* disable the editor */
call hmDisableRefresh

/* find the start and stop points for searching for the date */
/* these are so we don't accidentally modify the wrong text */
start = hmFind(starttext,0,,1)
if start=-1 then call notfound
stop = hmFind(stoptext,start,,1)
if stop=-1 then call notfound

/* select the text that will be replaced */
call hmSetSel start,stop-length(stoptext)

/* insert the new date */
call hmInsert date()

/* inform user of success */
call hmStatusSay "Updated AUTODATE!",40

/* exit the macro */
call hmEnableRefresh
exit

/* this procedure is called when one of the expected strings is not found */
notfound: procedure
    call hmStatusSay "Couldn't find AUTODATE!",40
    call hmEnableRefresh
    exit